<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<title>ColumnProvider</title>
		<link type="text/css" rel="stylesheet" href="PLUGINS_ROOT/org.polarsys.capella.doc/html/styles.css"/>
	</head>
	<body>
		<h1 id="Column_Provider">Column Provider</h1>
		<h2 id="Introduction">Introduction</h2>
		<p>The column provider extension point allows you to contribute new columns that will be automatically added to the existing ones.</p>
		<p>The interface associated to this extension point is <code>IMAColumnProvider</code>, but you should avoid implementing this interface directly and instead extend the <code>AbstractMAColumnProvider</code> class.</p>
		<p>The only method you need to implement is the <code>getColumns</code> method, which takes a collection of <code>PossibleFeatures</code> (containing all the common
				 structural features for the initial data objects, already computed for your use) and a collection of <code>EObject</code> elements (the current data objects for which the columns should be provided), and returns a collection of <code>IMAColumn</code>s.</p>
		<p>Note that this method is called every time new elements are added into the existing table (since the table configuration might change) in order to obtain the new column configuration (some elements that do not share a column with the existing ones might be added, and so this column should be removed). It is your responsibility to ensure that this method call is optimized, avoid recreating new columns if the existing ones did not change.</p>
		<p>
			<b>For the next concepts that we will introduce regarding the IMAColumn, we will always have the following naming convention</b>:
		</p>
		<ul>
			<li>
				<b>AbstractMA</b>ClassName: you should extend this class if your column 
				<b>is not</b> based on a EStructuralFeature, and instead uses its own data structure to manage the column content.
			</li>
		</ul>
		<ul>
			<li>
				<b>AbstractMAPrimitive</b>ClassName: you should extend this class if your column 
				<b>is</b> based on a EstructuralFeature, and uses the EObject feature directly to manage the column content.  
			</li>
		</ul>
		<h2 id="The_column_abstraction">The column abstraction</h2>
		<p>Represents a column abstraction that corresponds to a displayed column. Its main role is to manage the column data (obtaining the current value of this column for a particular table row and modifying it accordingly).</p>
		<p>It is advised that you do not implement this interface directly, and instead inherit of either link <code>AbstractMAColumn</code> or <code>MAPrimitiveColumn</code>.</p>
		<p>The <code>IMAColumn</code> is in charge among other things, of providing for each row object the current value for this column and also to update the existing value when the user has selected a new one. Note that if your column is not mapped to a feature, you need to use an internal data structure to manage the column content. You should typically use a hash-map having as many entries as row objects, but the choice belongs to you.</p>
		<h3 id="The_Cell_Editor">The Cell Editor</h3>
		<p>The cell editor is a NatTable concept, that wraps SWT controls to be cell editors. We provide two abstract implementations <code>AbstractMACellEditor</code> and <code>AbstractMAPrimitiveCellEditor</code>,  where we take care of most of the dirty work and internal plumbing.</p>
		<p>When the user click on an editable cell, the <code>createEditorControl</code> method is invoked and the newly created control is displayed in a dialog. The cell editor delegates all the display and editing behavior to this cell control.</p>
		<h4 id="The_Cell_Control">The Cell Control</h4>
		<p>We provide two abstract implementations <code>AbstractMACellControl</code> and <code>AbstractMAPrimitiveCellControl</code>. For both implementations you can use the <code>selectedRowObjects</code> field in order to have access to the row objects that the user selected when emitting an edit command. </p>
		<p>First of all please note that the control is a Composite, meaning that when the associated editor is invoked, a dialog containing this composite will be opened. By customizing this control you customize the way your users will select a new value for the cells they are currently editing. This can be as simple as a text field or as complex as a multi-grid dialog with plenty of buttons and sparkly colors.</p>
		<p>Second of all the control provides access to both the editor value (the representation displayed in the cell editor) and the canonical value (the normal data representation).</p>
		<p>For example, the canonical representation might be a Date object, whereas the editor representation could be a formatted String. 
			Note that in NatTable a new cell control is created whenever a user invokes an edit command.</p>
		<h3 id="The_Data_Validator">The Data Validator</h3>
		<p>The data validator provides a validation mechanism for the newly selected values by the users. If the validation is not successful, an error dialog is displayed and the user must either cancel or select a new value.</p>
		<p>You can extends the <code>MADataValidator</code> in order to add your own behavior.</p>
		<h3 id="The_Display_Converter">The Display Converter</h3>
		<p>The display converter converts between the actual object representation to the textual representation. The textual value is the one displayed in the column cell. For example, the canonical representation might be a Date object, whereas the target representation could be a formatted String.</p>
		<p>You can extends the <code>MADisplayConverter</code> in order to add your own behavior.</p>
	</body>
</html>